/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License"),
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup TeeTrusted
 * @{
 *
 * @brief TEE（Trusted Excution Environment）可信执行环境API。
 *
 * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。
 *
 * @since 20
 */

/**
 * @file tee_sharemem_ops.h
 *
 * @brief 为开发者提供申请共享内存的API。
 *
 * @library NA
 * @kit TEEKit
 * @include <TEEKit/tee_sharemem_ops.h>
 * @syscap SystemCapability.Tee.TeeClient
 * @since 20
 */

#ifndef TEE_SHAREMEM_OPS_H
#define TEE_SHAREMEM_OPS_H

#include <stdint.h>
#include <tee_defines.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 在TEE中分配共享内存。
 *
 * @param uuid 指示TA的UUID。
 * @param size 指示请求的共享内存大小。
 *
 * @return 如果操作成功，返回指向新分配空间的指针。\n
 *         如果分配失败，返回NULL指针。
 * @since 20
 */
void *tee_alloc_sharemem_aux(const struct tee_uuid *uuid, uint32_t size);

/**
 * @brief 在TEE中分配连续共享内存。
 *
 * @param uuid 指示TA的UUID。
 * @param size 指示请求的共享内存大小。
 *
 * @return 如果操作成功，返回指向新分配空间的指针。\n
 *         如果分配失败，返回NULL指针。
 * @since 20
 */
void *tee_alloc_coherent_sharemem_aux(const struct tee_uuid *uuid, uint32_t size);

/**
 * @brief 释放TEE中的共享内存。
 *
 * @param addr 指示将被释放的共享内存地址。
 * @param size 指示共享内存的大小。
 *
 * @return 如果操作成功，返回0。\n
 *         如果操作失败，返回其他值。
 * @since 20
 */
uint32_t tee_free_sharemem(void *addr, uint32_t size);

/**
 * @brief 从源任务复制共享内存。
 *
 * @param src_task 指示源任务的pid。
 * @param src 指示源缓冲区的地址。
 * @param src_size 指示源缓冲区的大小。
 * @param dst 指示目标缓冲区的地址。
 * @param dst_size 指示目标缓冲区的大小。
 *
 * @return 如果操作成功，返回0。\n
 *         如果操作失败，返回-1。
 * @since 20
 */
int32_t copy_from_sharemem(uint32_t src_task, uint64_t src, uint32_t src_size, uintptr_t dst, uint32_t dst_size);

/**
 * @brief 将共享内存复制到目标任务。
 *
 * @param src 指示源缓冲区的地址。
 * @param src_size 指示源缓冲区的大小。
 * @param dst_task 指示目标任务的pid。
 * @param dst 指示目标缓冲区的地址。
 * @param dst_size 指示目标缓冲区的大小。
 *
 * @return 如果操作成功，返回0。\n
 *         如果操作失败，返回-1。
 * @since 20
 */
int32_t copy_to_sharemem(uintptr_t src, uint32_t src_size, uint32_t dst_task, uint64_t dst, uint32_t dst_size);

#ifdef __cplusplus
}
#endif

#endif
/** @} */